Inside Macintosh: QuickDraw GX Printing /

Chapter 4 - Advanced Printing Features / About Advanced Printing Features

Synonyms

You can use synonyms to provide alternative printing directives instead of those generated by QuickDraw GX. You are never required to use a synonym. They are available for you to use if you want to explicitly control the way that QuickDraw GX renders output.

For example, if you have special-purpose PostScript code for printing a shape and wish to use it instead of the PostScript code that QuickDraw GX produces, you can create a synonym for your code and attach it to the shape object. When the shape is printed, the instructions associated with the synonym can be used to render the output.

If you use a synonym, the printer driver also must support its use; otherwise, the synonym is ignored. The synonym is interpreted by the printer driver; thus one printer driver may choose to implement a synonym using PostScript and another printer driver might use a proprietary language to implement the same synonym.

You use a synonym by creating a tag object and setting up a reference to that tag in the shape object or another kind of object. A tag object is a QuickDraw GX object that provides you with the ability to associate data with objects, such as shapes, styles, inks, colors, and transforms. For more information about tag objects, see the tag objects chapter of Inside Macintosh: QuickDraw GX Objects.

QuickDraw GX provides five kinds of synonyms:

• Direct PostScript synonyms, which allow you to explicitly specify PostScript operators for rendering images. You can use these synonyms with shape, style, ink, and transform objects to control the behavior of these objects when printing.
• Style synonyms, such as dashes, line caps, or patterns that can be associated with style objects.
• Halftone synonyms, which specify the halftone to be applied when a shape or page is printed. For general information about halftones, see the view-related objects chapter of Inside Macintosh: QuickDraw GX Objects.
• Cubic synonyms, which provide alternative directives for rendering path shapes. For information about path shapes, see the geometric shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
• Picture synonyms, which specify QuickDraw picture data for rendering pages. For example, QuickDraw GX uses picture synonyms to spool the output of documents designed for printing with the Macintosh Printing Manager.

Note

Synonyms remain with the shape or a related object, such as the shape's ink, style, or transform. If you cut or copy a shape and then paste it, the synonyms in the tag objects associated with the shape move with the shape. Synonyms also stay with the shape if the print file that contains the shape is redirected.

Table 4-2 identifies the synonyms that QuickDraw GX provides.

Table 4-2 QuickDraw GX printing synonyms

Constant	Value	Explanation
gxPostScriptTag	'post'	Specifies PostScript operators
gxPostControlTag	'psct'	Specifies control information for a PostScript printer
gxDashSynonymTag	'sdsh'	Specifies dashes, for example, with the PostScript setdash operator
gxLineCapSynonymTag	'lcap'	Specifies line caps, for example, with the PostScript setlinecap operator
gxPatternSynonymTag	'ptrn'	Specifies a pattern, for example, on vector devices
gxFormatHalftoneTag	'half'	Specifies halftones, for example, the PostScript halftone graphics state
gxCubicSynonymTag	'cubx'	Specifies a cubic representation for a path
gxQuickDrawPictTag	'pict'	Specifies a shape in QuickDraw picture format

The following sections describe the contents of the tag objects that you create for each of these synonyms. For an example of how to use a synonym, see "Using Synonyms," which begins on page 4-38.

General-Purpose PostScript Operator Synonym

If you want QuickDraw GX to use your own PostScript operators for rendering an object, you may create a gxPostScriptTag synonym and attach it to the object. If you only need to specify specific operators or set up the halftone graphics state, you may be able to use one of the special-purpose synonyms listed in Table 4-2.

You can reference a tag object that contains the gxPostScriptTag synonym from a shape object, style object, ink object, or transform object. The kind of object that references the tag object controls the kind of PostScript operators you can use.

• With a shape object, you can use PostScript printing operators to render the shape.
• With a style object, you can use PostScript operators to define all stylistic characteristics for the shapes that refer to the style object.
• With an ink object, you can use PostScript operators to define the color and transfer mode for the shapes that refer to the ink object.
• With a transform object, you can use PostScript operators to define the clip and mapping of the shapes that refer to the transform object. The gxPostScriptTag synonym may be ignored under certain conditions, such as when a transform object's mapping changes the perspective.

The data in the gxPostScriptTag synonym is pure PostScript code that is generated as one continuous PostScript data stream. There is no data type that defines the structure of this synonym. You can attach multiple tag objects to an object. This allows you to distribute data into smaller, more manageable pieces that require less memory to load. For best results, you should limit the data in a gxPostScriptTag synonym to 8 KB.

If you choose to write your own PostScript code, it is extremely important to make your PostScript code portable, especially if users create portable digital documents. To create portable PostScript code, try to follow these guidelines:

• Write PostScript code so that it runs on output devices that support Level 1 and devices that support Level 2.
• Do not make assumptions about the current "PostScript state" of the output device.
• Do not make assumptions about the fonts that are installed in the output device.

Note

The y-axis of the QuickDraw GX coordinate system is the reverse of the y-axis of the PostScript coordinate system.

PostScript Control Information Synonym

A shape object can refer to a tag object that contains the gxPostControlTag synonym. The synonym includes flags that indicate how to modify the PostScript graphics state.

The gxPostControlTag synonym provides data specific to PostScript devices that may be necessary for these devices to properly render the data contained within the gxPostScriptTag synonym. You are not required, however, to have a gxPostControlTag synonym when you use gxPostScriptTag synonyms.

A shape object can refer to, at most, only one gxPostControlTag synonym. Information in this synonym affects all gxPostScriptTag synonyms attached to a shape object.

The gxPostControl structure defines the contents of a gxPostControlTag synonym:

struct gxPostControl {
   long flags;                
};

Field Description

flags

A flag that specifies how a shape is embedded in the PostScript data stream. If it is gxNoSave, the PostScript data should be encapsulated between a save and restore combination. If gxNoSave is not specified or the gxPostControlTag synonym is not present, the save and restore combination is used.

Dash Synonym

A style object can refer to a tag that contains the gxDashSynonymTag synonym. This tag causes QuickDraw GX to print simple dashes. For example, this synonym may cause the printer driver to use the PostScript setdash operator instead of the specification in the dash property of the style. The phase for the setdash operator might still be taken from the phase value stored in the dash property of the style object.

The gxDashSynonym structure defines the contents of a gxDashSynonymTag synonym:

struct gxDashSynonym {
   long size;                    
   fixed dashLength[gxAnyNumber];
};

Field Description

size

The number of elements in a dash array.

dashLength

An array of lengths for the dashes.

Line Cap Synonym

A style object can refer to a tag that contains the gxLineCapSynonym synonym. For example, this synonym may cause the printer driver to print with the PostScript linecap operator instead of the specification in the cap property of the style.

The gxLineCapSynonym structure defines the gxLineCapSynonymTag synonym:

typedef long gxLineCapSynonym;

The structure is a long word that specifies one of the values in the gxLineCaps enumeration:

enum gxLineCaps{
   gxButtCap = 0,          
   gxRoundCap = 1,         
   gxSquareCap = 2,        
   gxTriangleCap = 3       
};

Constant descriptions

gxButtCap

Use a square cap, such as the PostScript butt cap, for the line cap.

gxRoundCap

Use a round cap, such as the PostScript round cap, for the line cap.

gxSquareCap

Use a square cap, such as the PostScript projecting square cap, for the line cap.

gxTriangleCap

Use a triangle cap.

Halftone Synonym

QuickDraw GX supports halftones to represent more colors than can be represented on a printer by alternating available colors in a fixed cell size to represent more colors. QuickDraw GX, by default, chooses the appropriate halftone for you; however, you can choose to specify halftone information on a shape-by-shape or page-by-page basis yourself.

To provide halftone information for a particular shape object, the shape's ink object must refer to a tag object that contains the gxFormatHalftoneTag synonym. This allows halftones to be specified for individual inks. Shapes that are drawn with the same ink use the same halftone. An ink that does not refer to the gxFormatHalftoneTag synonym uses the page's halftone.

Note

If you specify halftone information on a page-by-page basis, you use the format-halftone property in the format collection associated with the page's format. For more information about this property, see the chapter "Page Formatting and Dialog Box Customization" in this book.

The gxFormatHalftoneInfo structure defines the contents of a gxFormatHalftoneTag synonym:

struct gxFormatHalftoneInfo {
   long        numHalftones;  
   gxHalftone  halftones[1];  
};

Field Description

numHalftones

The number of halftones available for use.

halftones

The array of halftone specifications.

Halftones are specified in the gxHalftone structures, which are described completely in the view-related objects chapter of Inside Macintosh: QuickDraw GX Objects:

struct gxHalftone{
   fixed          angle;            /* direction of halftone */
   fixed          frequency;        /* cells per inch */
   gxDotType      method;           /* kind of pattern */
   gxTintType     tinting;          /* tint calculation method */
   gxColor        dotColor;         /* color of foreground */
   gxColor        backgroundColor;  /* color of background */
   gxColorSpace   tintSpace;        /* color space for tint */
};

You can specify any number of halftones. QuickDraw GX selects appropriate halftones from the list of available halftones. Its selection is based upon the tinting field in the halftone structures:

• When you print to a black-and-white PostScript device, QuickDraw GX looks for a halftone structure that specifies gxLuminanceTint in the tinting field. If no halftone specifies this value, it looks for a halftone specifies gxComponent4Tint as its tinting method. Component 4 is the black component in the CMYK (cyan, magenta, yellow, and black) space. If no halftone specifies this tinting method either, the first halftone in the list is used.
• When you print to a color PostScript device, a maximum of four halftones are used. QuickDraw GX attempts to locate halftones for the following tint calculation methods: gxComponent1Tint for the cyan halftone, gxComponent2Tint for the magenta halftone, gxComponent3Tint field for the yellow halftone, and gxComponent4Tint for the black halftone. If a tinting method is in the list more than once, the first one in the list is used.

  If a halftone for the gxComponent4Tint method is not in the list, QuickDraw GX uses the gxLuminanceTint tinting method for the black halftone. If the gxLuminanceTint tinting method cannot be found either, QuickDraw GX uses the first halftone in the list for the black halftone.

  If QuickDraw GX cannot find a halftone for the gxComponent1Tint, gxComponent2Tint, or gxComponent3Tint tinting methods, it uses the black halftone for the missing tinting method.

It is only possible to use halftones to the extent that a particular PostScript device supports them. The dot color and background color of a halftone are ignored because QuickDraw GX assumes that the dot color for a black-and-white device is black and the dot color for a color device with the gxComponent2Tint tinting method is magenta.

Note

Continuous tone output devices, such as a 32-bit color printer, may choose to ignore the halftone synonym because halftones are not needed on these output devices.

Pattern Synonym

A style object can refer to a tag object that contains the gxPatternSynonymTag synonym. This synonym causes QuickDraw GX to print with the pattern specified in the tag instead of the specification in the pattern property of the style. For example, vector devices typically support crosshatch patterns.

The gxPatternSynonymTag structure defines the contents of a gxPatternSynonymTag synonym:

struct gxPatternSynonym {
   long     patternType;      
   fixed    angle;            
   fixed    spacing;          
   fixed    thickness;        
   gxPoint  anchorPoint;      
};

Field Description

patternType

The pattern type, either gxHatch or gxCrossHatch.

angle

The angle of the lines in the pattern.

spacing

The distance between the lines in the pattern.

thickness

The thickness of the lines in the pattern.

anchorPoint

A point that specifies the upper-left corner at which the pattern begins.

Cubic Synonym

A path shape object can refer to a tag object that contains the gxCubicSynonymTag synonym. This synonym causes QuickDraw GX to print with a representation of the shape using cubics, such as Bezier curves, instead of the quadratic Bezier curves specified in the shape's geometry.

The data in this synonym is ignored, however, when

• it is attached to any shape object other than a path
• the shape object's transform hierarchy changes the perspective
• the shape object exceeds the PostScript point limit for the destination device
• the shape object is used as a pattern, dash, clip, cap, or join

The gxCubicSynonymTag synonym contains a stream of flags and points. The flags are specified in the gxCubicSynonym enumeration:

enum gxCubicSynonym{
   gxIgnoreFlag      =  0x0000,
   gxLineToFlag      =  0x0001,
   gxCurveToFlag     =  0x0002,
   gxMoveToFlag      =  0x0003,
   gxClosePathFlag   =  0x0004
};

Constant descriptions

gxIgnoreFlag

Ignore this flag; get the next one.

gxLineToFlag

Draw a line from the current point to the point specified after this flag.

gxCurveToFlag

Draw a curve from the current point through the three points specified after this flag.

gxMoveToFlag

Move the start of a new contour, which becomes the current point, to the point specified after this flag.

gxClosePathFlag

Close the contour.

The point, line, or curve specified after a line follow the conventions for a point, line, or curve, (gxPoint, gxLine, or gxCurve), respectively. The rendering of the shape still depends on the fill of the shape object and the shape object's style, ink, and transform.

Each flag is a short integer; however, QuickDraw GX only considers the low 8 bits. Your application can store application-specific flags in the other 8 bits of the word. Set bits that are not used to 0.

QuickDraw Picture Synonym

When QuickDraw GX spools a document containing QuickDraw imaging commands, it creates and flattens, for each page, a QuickDraw GX rectangle shape with an attached tag object of tag type 'pict' (the QuickDraw GX constant for that tag type is gxQuickDrawPictTag). The tag object contains information that specifies the characteristics and location of a file containing QuickDraw picture data for that page.

When QuickDraw GX subsequently despools the file, it (or the printer driver) uses the QuickDraw GX Translator to convert the QuickDraw picture data into a QuickDraw GX picture shape before printing it. The tag object contains a gxQuickDrawPict structure:

struct gxQuickDrawPict {
   gxTranslationOptions             options;
   Rect                             srcRect;
   Point                            styleStretch;
   unsigned long                    dataLength;
   struct gxBitmapDataSourceAlias   alias;
};

Field Description

options

The translation options to be used by the QuickDraw GX Translator when converting the QuickDraw data.

srcRect

The source rectangle for the translation, in QuickDraw coordinates. It controls scaling of the image. This rectangle is the QuickDraw picture frame that bounds the QuickDraw data.

styleStretch

The scale factor (both horizontal and vertical) to apply to certain items, such as dashes, in QuickDraw picture comments.

dataLength

The length of the QuickDraw picture data, in bytes.

alias

A structure that defines the location of the file containing the QuickDraw data, and the offset within the file to that data.

The QuickDraw GX rectangle shape that the tag object is attached to specifies the destination bounding rectangle for drawing the QuickDraw data (in QuickDraw coordinates). The relative sizes of the source rectangle and destination rectangle control the scaling of the image when it is translated.

The QuickDraw GX Translator is described in the environment chapter of Inside Macintosh: QuickDraw GX Environment and Utilities. Tag objects are described in the tag objects chapter of Inside Macintosh: QuickDraw GX Objects. The gxBitmapDataSourceAlias structure is described in the bitmap shapes chapter of Inside Macintosh: QuickDraw GX Graphics. QuickDraw picture data is described in Inside Macintosh: Imaging With QuickDraw.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help